---
order: 3
title: Sprite Mask
type: Graphics
group: 2D
label: Graphics/2D
---

The Sprite Mask component is used to apply masking effects to [Sprite Renderer](/en/docs/graphics/2D/spriteRenderer/) and [Text Renderer](/en/docs/graphics/2D/text/) in 3D/2D scenes.

<Playground href="/embed/sprite-mask" />

Control the interaction with [Sprite](/en/docs/graphics/2D/sprite/) using parameters provided by [SpriteMask](/apis/core/#SpriteMask).

| Parameter       | Type   | Description                                                                                      |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------- |
| influenceLayers | number | The mask layers affected by the current mask. Default is SpriteMaskLayer.Everything, meaning it affects all mask layers. |
| alphaCutoff     | number | The lower limit of the effective alpha value for the current mask (range: 0~1). Pixels with alpha values less than alphaCutoff will be discarded. |

[SpriteMaskLayer](/apis/core/#SpriteMaskLayer) declares the mask layers provided by the engine. There are 32 mask layers in total, named Layer0~Layer31. Mask layers are unrelated to rendering and are only used to help developers set how `SpriteMask` and `SpriteRenderer` interact. For a `SpriteMask` object to mask a `SpriteRenderer` object, their mask layers must intersect.

The `influenceLayers` of `SpriteMask` indicates which mask layers the mask will affect for `SpriteRenderer`. The `maskLayer` of `SpriteRenderer` indicates which mask layers the sprite belongs to, as shown below:

<Image src="https://gw.alipayobjects.com/zos/OasisHub/09abdf57-84b8-4aa9-b785-822f858fb4f9/070C8B9F-14E2-4A9A-BFEC-4BC3F2BB564F.png" alt="070C8B9F-14E2-4A9A-BFEC-4BC3F2BB564F" style={{zoom:"67%"}} />

In the image above, the spriteMask affects sprites in `Layer1` and `Layer30`. spriteRenderer0 is in `Layer2`, so there is no intersection, and spriteRenderer0 does not interact with spriteMask. spriteRenderer1 is in `Layer1`, which intersects with the mask layers affected by spriteMask, so spriteRenderer1 interacts with spriteMask.

## Usage

### Adding a Sprite Mask Component

When we need to mask a sprite, we first need to create an entity and add a sprite mask component, as shown below:

<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*GYVBTbTvqU4AAAAAAAAAAAAADjCHAQ/original" />

### Setting the Mask Area

The sprite mask component uses an image to represent the mask area. We set the sprite resource through the component's `sprite` parameter, as shown below:

<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*k5GsSYqQTKoAAAAAAAAAAAAADjCHAQ/original" />

### Setting the Sprite's Mask Type

After the above two steps, you may find that the mask still has no effect. This is because the current sprite's mask type is still the default (None). We set the `mask interaction` of the sprite in the scene to the inner mask type, as shown below:

<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*GdxhSYLY4EIAAAAAAAAAAAAADjCHAQ/original" />

### Setting alpha cutoff

This parameter represents the lower limit of the effective `alpha` value for the current mask (range: `0~1`). In other words, any alpha value in the sprite's texture that is less than the alpha cutoff will be discarded (i.e., it will not be considered as a mask area). We can dynamically adjust the value of this property to see the actual effect, as shown below:

<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*2CLjT7UTVa8AAAAAAAAAAAAADjCHAQ/original" />

Similarly, in the script, we can use the following code to apply the sprite mask:

```typescript
// 创建一个遮罩实体
const spriteEntity = rootEntity.createChild(`spriteMask`);
// 给实体添加 SpriteMask 组件
const spriteMask = spriteEntity.addComponent(SpriteMask);
// 通过 texture 创建 sprite 对象
const sprite = new Sprite(engine, texture);
// 设置 sprite
spriteMask.sprite = sprite;
// mask 的 sprite 中纹理 alpha 小于 0.5 的将被丢弃
spriteMask.alphaCutoff = 0.5;
// mask 对所有遮罩层的精灵都生效
spriteMask.influenceLayers = SpriteMaskLayer.Everything;
// mask 只对处于遮罩层 Layer0 的精灵有效
spriteMask.influenceLayers = SpriteMaskLayer.Layer0;
// mask 对处于遮罩层 Layer0 和 Layer1 的精灵有效
spriteMask.influenceLayers = SpriteMaskLayer.Layer0 | SpriteMaskLayer.Layer1;

// 设置遮罩类型
spriteRenderer.maskInteraction = SpriteMaskInteraction.VisibleInsideMask;
// 设置精灵处于哪个遮罩层
spriteRenderer.maskLayer = SpriteMaskLayer.Layer0;
```
